.TH "TiXmlHandle" 3 "13 Oct 2009" "Version 2" "zebulon" \" -*- nroff -*-
.ad l
.nh
.SH NAME
TiXmlHandle \- 
.SH SYNOPSIS
.br
.PP
.PP
\fC#include <tinyxml.h>\fP
.SS "Public Member Functions"

.in +1c
.ti -1c
.RI "\fBTiXmlHandle\fP (\fBTiXmlNode\fP *_node)"
.br
.RI "\fICreate a handle from any node (at any depth of the tree.) This can be a null pointer. \fP"
.ti -1c
.RI "\fBTiXmlHandle\fP (const \fBTiXmlHandle\fP &ref)"
.br
.RI "\fICopy constructor. \fP"
.ti -1c
.RI "\fBTiXmlHandle\fP \fBoperator=\fP (const \fBTiXmlHandle\fP &ref)"
.br
.ti -1c
.RI "\fBTiXmlHandle\fP \fBFirstChild\fP () const "
.br
.RI "\fIReturn a handle to the first child node. \fP"
.ti -1c
.RI "\fBTiXmlHandle\fP \fBFirstChild\fP (const char *value) const "
.br
.RI "\fIReturn a handle to the first child node with the given name. \fP"
.ti -1c
.RI "\fBTiXmlHandle\fP \fBFirstChildElement\fP () const "
.br
.RI "\fIReturn a handle to the first child element. \fP"
.ti -1c
.RI "\fBTiXmlHandle\fP \fBFirstChildElement\fP (const char *value) const "
.br
.RI "\fIReturn a handle to the first child element with the given name. \fP"
.ti -1c
.RI "\fBTiXmlHandle\fP \fBChild\fP (const char *value, int index) const "
.br
.ti -1c
.RI "\fBTiXmlHandle\fP \fBChild\fP (int index) const "
.br
.ti -1c
.RI "\fBTiXmlHandle\fP \fBChildElement\fP (const char *value, int index) const "
.br
.ti -1c
.RI "\fBTiXmlHandle\fP \fBChildElement\fP (int index) const "
.br
.ti -1c
.RI "\fBTiXmlNode\fP * \fBToNode\fP () const "
.br
.ti -1c
.RI "\fBTiXmlElement\fP * \fBToElement\fP () const "
.br
.ti -1c
.RI "\fBTiXmlText\fP * \fBToText\fP () const "
.br
.ti -1c
.RI "\fBTiXmlUnknown\fP * \fBToUnknown\fP () const "
.br
.ti -1c
.RI "\fBTiXmlNode\fP * \fBNode\fP () const "
.br
.ti -1c
.RI "\fBTiXmlElement\fP * \fBElement\fP () const "
.br
.ti -1c
.RI "\fBTiXmlText\fP * \fBText\fP () const "
.br
.ti -1c
.RI "\fBTiXmlUnknown\fP * \fBUnknown\fP () const "
.br
.ti -1c
.RI "\fBTiXmlHandle\fP (\fBTiXmlNode\fP *_node)"
.br
.RI "\fICreate a handle from any node (at any depth of the tree.) This can be a null pointer. \fP"
.ti -1c
.RI "\fBTiXmlHandle\fP (const \fBTiXmlHandle\fP &ref)"
.br
.RI "\fICopy constructor. \fP"
.ti -1c
.RI "\fBTiXmlHandle\fP \fBoperator=\fP (const \fBTiXmlHandle\fP &ref)"
.br
.ti -1c
.RI "\fBTiXmlHandle\fP \fBFirstChild\fP () const "
.br
.RI "\fIReturn a handle to the first child node. \fP"
.ti -1c
.RI "\fBTiXmlHandle\fP \fBFirstChild\fP (const char *value) const "
.br
.RI "\fIReturn a handle to the first child node with the given name. \fP"
.ti -1c
.RI "\fBTiXmlHandle\fP \fBFirstChildElement\fP () const "
.br
.RI "\fIReturn a handle to the first child element. \fP"
.ti -1c
.RI "\fBTiXmlHandle\fP \fBFirstChildElement\fP (const char *value) const "
.br
.RI "\fIReturn a handle to the first child element with the given name. \fP"
.ti -1c
.RI "\fBTiXmlHandle\fP \fBChild\fP (const char *value, int index) const "
.br
.ti -1c
.RI "\fBTiXmlHandle\fP \fBChild\fP (int index) const "
.br
.ti -1c
.RI "\fBTiXmlHandle\fP \fBChildElement\fP (const char *value, int index) const "
.br
.ti -1c
.RI "\fBTiXmlHandle\fP \fBChildElement\fP (int index) const "
.br
.ti -1c
.RI "\fBTiXmlNode\fP * \fBToNode\fP () const "
.br
.ti -1c
.RI "\fBTiXmlElement\fP * \fBToElement\fP () const "
.br
.ti -1c
.RI "\fBTiXmlText\fP * \fBToText\fP () const "
.br
.ti -1c
.RI "\fBTiXmlUnknown\fP * \fBToUnknown\fP () const "
.br
.ti -1c
.RI "\fBTiXmlNode\fP * \fBNode\fP () const "
.br
.ti -1c
.RI "\fBTiXmlElement\fP * \fBElement\fP () const "
.br
.ti -1c
.RI "\fBTiXmlText\fP * \fBText\fP () const "
.br
.ti -1c
.RI "\fBTiXmlUnknown\fP * \fBUnknown\fP () const "
.br
.ti -1c
.RI "\fBTiXmlHandle\fP (\fBTiXmlNode\fP *_node)"
.br
.RI "\fICreate a handle from any node (at any depth of the tree.) This can be a null pointer. \fP"
.ti -1c
.RI "\fBTiXmlHandle\fP (const \fBTiXmlHandle\fP &ref)"
.br
.RI "\fICopy constructor. \fP"
.ti -1c
.RI "\fBTiXmlHandle\fP \fBoperator=\fP (const \fBTiXmlHandle\fP &ref)"
.br
.ti -1c
.RI "\fBTiXmlHandle\fP \fBFirstChild\fP () const "
.br
.RI "\fIReturn a handle to the first child node. \fP"
.ti -1c
.RI "\fBTiXmlHandle\fP \fBFirstChild\fP (const char *value) const "
.br
.RI "\fIReturn a handle to the first child node with the given name. \fP"
.ti -1c
.RI "\fBTiXmlHandle\fP \fBFirstChildElement\fP () const "
.br
.RI "\fIReturn a handle to the first child element. \fP"
.ti -1c
.RI "\fBTiXmlHandle\fP \fBFirstChildElement\fP (const char *value) const "
.br
.RI "\fIReturn a handle to the first child element with the given name. \fP"
.ti -1c
.RI "\fBTiXmlHandle\fP \fBChild\fP (const char *value, int index) const "
.br
.ti -1c
.RI "\fBTiXmlHandle\fP \fBChild\fP (int index) const "
.br
.ti -1c
.RI "\fBTiXmlHandle\fP \fBChildElement\fP (const char *value, int index) const "
.br
.ti -1c
.RI "\fBTiXmlHandle\fP \fBChildElement\fP (int index) const "
.br
.ti -1c
.RI "\fBTiXmlNode\fP * \fBToNode\fP () const "
.br
.ti -1c
.RI "\fBTiXmlElement\fP * \fBToElement\fP () const "
.br
.ti -1c
.RI "\fBTiXmlText\fP * \fBToText\fP () const "
.br
.ti -1c
.RI "\fBTiXmlUnknown\fP * \fBToUnknown\fP () const "
.br
.ti -1c
.RI "\fBTiXmlNode\fP * \fBNode\fP () const "
.br
.ti -1c
.RI "\fBTiXmlElement\fP * \fBElement\fP () const "
.br
.ti -1c
.RI "\fBTiXmlText\fP * \fBText\fP () const "
.br
.ti -1c
.RI "\fBTiXmlUnknown\fP * \fBUnknown\fP () const "
.br
.ti -1c
.RI "\fBTiXmlHandle\fP (\fBTiXmlNode\fP *_node)"
.br
.RI "\fICreate a handle from any node (at any depth of the tree.) This can be a null pointer. \fP"
.ti -1c
.RI "\fBTiXmlHandle\fP (const \fBTiXmlHandle\fP &ref)"
.br
.RI "\fICopy constructor. \fP"
.ti -1c
.RI "\fBTiXmlHandle\fP \fBoperator=\fP (const \fBTiXmlHandle\fP &ref)"
.br
.ti -1c
.RI "\fBTiXmlHandle\fP \fBFirstChild\fP () const "
.br
.RI "\fIReturn a handle to the first child node. \fP"
.ti -1c
.RI "\fBTiXmlHandle\fP \fBFirstChild\fP (const char *value) const "
.br
.RI "\fIReturn a handle to the first child node with the given name. \fP"
.ti -1c
.RI "\fBTiXmlHandle\fP \fBFirstChildElement\fP () const "
.br
.RI "\fIReturn a handle to the first child element. \fP"
.ti -1c
.RI "\fBTiXmlHandle\fP \fBFirstChildElement\fP (const char *value) const "
.br
.RI "\fIReturn a handle to the first child element with the given name. \fP"
.ti -1c
.RI "\fBTiXmlHandle\fP \fBChild\fP (const char *value, int index) const "
.br
.ti -1c
.RI "\fBTiXmlHandle\fP \fBChild\fP (int index) const "
.br
.ti -1c
.RI "\fBTiXmlHandle\fP \fBChildElement\fP (const char *value, int index) const "
.br
.ti -1c
.RI "\fBTiXmlHandle\fP \fBChildElement\fP (int index) const "
.br
.ti -1c
.RI "\fBTiXmlNode\fP * \fBToNode\fP () const "
.br
.ti -1c
.RI "\fBTiXmlElement\fP * \fBToElement\fP () const "
.br
.ti -1c
.RI "\fBTiXmlText\fP * \fBToText\fP () const "
.br
.ti -1c
.RI "\fBTiXmlUnknown\fP * \fBToUnknown\fP () const "
.br
.ti -1c
.RI "\fBTiXmlNode\fP * \fBNode\fP () const "
.br
.ti -1c
.RI "\fBTiXmlElement\fP * \fBElement\fP () const "
.br
.ti -1c
.RI "\fBTiXmlText\fP * \fBText\fP () const "
.br
.ti -1c
.RI "\fBTiXmlUnknown\fP * \fBUnknown\fP () const "
.br
.in -1c
.SH "Detailed Description"
.PP 
A \fBTiXmlHandle\fP is a class that wraps a node pointer with null checks; this is an incredibly useful thing. Note that \fBTiXmlHandle\fP is not part of the TinyXml DOM structure. It is a separate utility class.
.PP
Take an example: 
.PP
.nf

	<Document>
		<Element attributeA = "valueA">
			<Child attributeB = "value1" />
			<Child attributeB = "value2" />
		</Element>
	<Document>
	
.fi
.PP
.PP
Assuming you want the value of 'attributeB' in the 2nd 'Child' element, it's very easy to write a *lot* of code that looks like:
.PP
.PP
.nf

	TiXmlElement* root = document.FirstChildElement( "Document" );
	if ( root )
	{
		TiXmlElement* element = root->FirstChildElement( "Element" );
		if ( element )
		{
			TiXmlElement* child = element->FirstChildElement( "Child" );
			if ( child )
			{
				TiXmlElement* child2 = child->NextSiblingElement( "Child" );
				if ( child2 )
				{
					// Finally do something useful.
	.fi
.PP
.PP
And that doesn't even cover 'else' cases. \fBTiXmlHandle\fP addresses the verbosity of such code. A \fBTiXmlHandle\fP checks for null pointers so it is perfectly safe and correct to use:
.PP
.PP
.nf

	TiXmlHandle docHandle( &document );
	TiXmlElement* child2 = docHandle.FirstChild( "Document" ).FirstChild( "Element" ).Child( "Child", 1 ).ToElement();
	if ( child2 )
	{
		// do something useful
	.fi
.PP
.PP
Which is MUCH more concise and useful.
.PP
It is also safe to copy handles - internally they are nothing more than node pointers. 
.PP
.nf

	TiXmlHandle handleCopy = handle;
	
.fi
.PP
.PP
What they should not be used for is iteration:
.PP
.PP
.nf

	int i=0; 
	while ( true )
	{
		TiXmlElement* child = docHandle.FirstChild( "Document" ).FirstChild( "Element" ).Child( "Child", i ).ToElement();
		if ( !child )
			break;
		// do something
		++i;
	}
	.fi
.PP
.PP
It seems reasonable, but it is in fact two embedded while loops. The Child method is a linear walk to find the element, so this code would iterate much more than it needs to. Instead, prefer:
.PP
.PP
.nf

	TiXmlElement* child = docHandle.FirstChild( "Document" ).FirstChild( "Element" ).FirstChild( "Child" ).ToElement();

	for( child; child; child=child->NextSiblingElement() )
	{
		// do something
	}
	.fi
.PP
 
.SH "Member Function Documentation"
.PP 
.SS "\fBTiXmlHandle\fP TiXmlHandle::Child (int index) const"Return a handle to the 'index' child. The first child is 0, the second 1, etc. 
.SS "\fBTiXmlHandle\fP TiXmlHandle::Child (const char * value, int index) const"Return a handle to the 'index' child with the given name. The first child is 0, the second 1, etc. 
.SS "\fBTiXmlHandle\fP TiXmlHandle::Child (int index) const"Return a handle to the 'index' child. The first child is 0, the second 1, etc. 
.SS "\fBTiXmlHandle\fP TiXmlHandle::Child (const char * value, int index) const"Return a handle to the 'index' child with the given name. The first child is 0, the second 1, etc. 
.SS "\fBTiXmlHandle\fP TiXmlHandle::Child (int index) const"Return a handle to the 'index' child. The first child is 0, the second 1, etc. 
.SS "\fBTiXmlHandle\fP TiXmlHandle::Child (const char * value, int index) const"Return a handle to the 'index' child with the given name. The first child is 0, the second 1, etc. 
.SS "\fBTiXmlHandle\fP TiXmlHandle::Child (int index) const"Return a handle to the 'index' child. The first child is 0, the second 1, etc. 
.SS "\fBTiXmlHandle\fP TiXmlHandle::Child (const char * value, int index) const"Return a handle to the 'index' child with the given name. The first child is 0, the second 1, etc. 
.SS "\fBTiXmlHandle\fP TiXmlHandle::ChildElement (int index) const"Return a handle to the 'index' child element. The first child element is 0, the second 1, etc. Note that only TiXmlElements are indexed: other types are not counted. 
.SS "\fBTiXmlHandle\fP TiXmlHandle::ChildElement (const char * value, int index) const"Return a handle to the 'index' child element with the given name. The first child element is 0, the second 1, etc. Note that only TiXmlElements are indexed: other types are not counted. 
.SS "\fBTiXmlHandle\fP TiXmlHandle::ChildElement (int index) const"Return a handle to the 'index' child element. The first child element is 0, the second 1, etc. Note that only TiXmlElements are indexed: other types are not counted. 
.SS "\fBTiXmlHandle\fP TiXmlHandle::ChildElement (const char * value, int index) const"Return a handle to the 'index' child element with the given name. The first child element is 0, the second 1, etc. Note that only TiXmlElements are indexed: other types are not counted. 
.SS "\fBTiXmlHandle\fP TiXmlHandle::ChildElement (int index) const"Return a handle to the 'index' child element. The first child element is 0, the second 1, etc. Note that only TiXmlElements are indexed: other types are not counted. 
.SS "\fBTiXmlHandle\fP TiXmlHandle::ChildElement (const char * value, int index) const"Return a handle to the 'index' child element with the given name. The first child element is 0, the second 1, etc. Note that only TiXmlElements are indexed: other types are not counted. 
.SS "\fBTiXmlHandle\fP TiXmlHandle::ChildElement (int index) const"Return a handle to the 'index' child element. The first child element is 0, the second 1, etc. Note that only TiXmlElements are indexed: other types are not counted. 
.SS "\fBTiXmlHandle\fP TiXmlHandle::ChildElement (const char * value, int index) const"Return a handle to the 'index' child element with the given name. The first child element is 0, the second 1, etc. Note that only TiXmlElements are indexed: other types are not counted. 
.SS "\fBTiXmlElement\fP* TiXmlHandle::Element () const\fC [inline]\fP"\fBDeprecated\fP
.RS 4
use ToElement. Return the handle as a \fBTiXmlElement\fP. This may return null. 
.RE
.PP

.SS "\fBTiXmlElement\fP* TiXmlHandle::Element () const\fC [inline]\fP"\fBDeprecated\fP
.RS 4
use ToElement. Return the handle as a \fBTiXmlElement\fP. This may return null. 
.RE
.PP

.SS "\fBTiXmlElement\fP* TiXmlHandle::Element () const\fC [inline]\fP"\fBDeprecated\fP
.RS 4
use ToElement. Return the handle as a \fBTiXmlElement\fP. This may return null. 
.RE
.PP

.SS "\fBTiXmlElement\fP* TiXmlHandle::Element () const\fC [inline]\fP"\fBDeprecated\fP
.RS 4
use ToElement. Return the handle as a \fBTiXmlElement\fP. This may return null. 
.RE
.PP

.SS "\fBTiXmlNode\fP* TiXmlHandle::Node () const\fC [inline]\fP"\fBDeprecated\fP
.RS 4
use ToNode. Return the handle as a \fBTiXmlNode\fP. This may return null. 
.RE
.PP

.SS "\fBTiXmlNode\fP* TiXmlHandle::Node () const\fC [inline]\fP"\fBDeprecated\fP
.RS 4
use ToNode. Return the handle as a \fBTiXmlNode\fP. This may return null. 
.RE
.PP

.SS "\fBTiXmlNode\fP* TiXmlHandle::Node () const\fC [inline]\fP"\fBDeprecated\fP
.RS 4
use ToNode. Return the handle as a \fBTiXmlNode\fP. This may return null. 
.RE
.PP

.SS "\fBTiXmlNode\fP* TiXmlHandle::Node () const\fC [inline]\fP"\fBDeprecated\fP
.RS 4
use ToNode. Return the handle as a \fBTiXmlNode\fP. This may return null. 
.RE
.PP

.SS "\fBTiXmlText\fP* TiXmlHandle::Text () const\fC [inline]\fP"\fBDeprecated\fP
.RS 4
use \fBToText()\fP Return the handle as a \fBTiXmlText\fP. This may return null. 
.RE
.PP

.SS "\fBTiXmlText\fP* TiXmlHandle::Text () const\fC [inline]\fP"\fBDeprecated\fP
.RS 4
use \fBToText()\fP Return the handle as a \fBTiXmlText\fP. This may return null. 
.RE
.PP

.SS "\fBTiXmlText\fP* TiXmlHandle::Text () const\fC [inline]\fP"\fBDeprecated\fP
.RS 4
use \fBToText()\fP Return the handle as a \fBTiXmlText\fP. This may return null. 
.RE
.PP

.SS "\fBTiXmlText\fP* TiXmlHandle::Text () const\fC [inline]\fP"\fBDeprecated\fP
.RS 4
use \fBToText()\fP Return the handle as a \fBTiXmlText\fP. This may return null. 
.RE
.PP

.SS "\fBTiXmlElement\fP* TiXmlHandle::ToElement () const\fC [inline]\fP"Return the handle as a \fBTiXmlElement\fP. This may return null. 
.SS "\fBTiXmlElement\fP* TiXmlHandle::ToElement () const\fC [inline]\fP"Return the handle as a \fBTiXmlElement\fP. This may return null. 
.SS "\fBTiXmlElement\fP* TiXmlHandle::ToElement () const\fC [inline]\fP"Return the handle as a \fBTiXmlElement\fP. This may return null. 
.SS "\fBTiXmlElement\fP* TiXmlHandle::ToElement () const\fC [inline]\fP"Return the handle as a \fBTiXmlElement\fP. This may return null. 
.SS "\fBTiXmlNode\fP* TiXmlHandle::ToNode () const\fC [inline]\fP"Return the handle as a \fBTiXmlNode\fP. This may return null. 
.SS "\fBTiXmlNode\fP* TiXmlHandle::ToNode () const\fC [inline]\fP"Return the handle as a \fBTiXmlNode\fP. This may return null. 
.SS "\fBTiXmlNode\fP* TiXmlHandle::ToNode () const\fC [inline]\fP"Return the handle as a \fBTiXmlNode\fP. This may return null. 
.SS "\fBTiXmlNode\fP* TiXmlHandle::ToNode () const\fC [inline]\fP"Return the handle as a \fBTiXmlNode\fP. This may return null. 
.SS "\fBTiXmlText\fP* TiXmlHandle::ToText () const\fC [inline]\fP"Return the handle as a \fBTiXmlText\fP. This may return null. 
.SS "\fBTiXmlText\fP* TiXmlHandle::ToText () const\fC [inline]\fP"Return the handle as a \fBTiXmlText\fP. This may return null. 
.SS "\fBTiXmlText\fP* TiXmlHandle::ToText () const\fC [inline]\fP"Return the handle as a \fBTiXmlText\fP. This may return null. 
.SS "\fBTiXmlText\fP* TiXmlHandle::ToText () const\fC [inline]\fP"Return the handle as a \fBTiXmlText\fP. This may return null. 
.SS "\fBTiXmlUnknown\fP* TiXmlHandle::ToUnknown () const\fC [inline]\fP"Return the handle as a \fBTiXmlUnknown\fP. This may return null. 
.SS "\fBTiXmlUnknown\fP* TiXmlHandle::ToUnknown () const\fC [inline]\fP"Return the handle as a \fBTiXmlUnknown\fP. This may return null. 
.SS "\fBTiXmlUnknown\fP* TiXmlHandle::ToUnknown () const\fC [inline]\fP"Return the handle as a \fBTiXmlUnknown\fP. This may return null. 
.SS "\fBTiXmlUnknown\fP* TiXmlHandle::ToUnknown () const\fC [inline]\fP"Return the handle as a \fBTiXmlUnknown\fP. This may return null. 
.SS "\fBTiXmlUnknown\fP* TiXmlHandle::Unknown () const\fC [inline]\fP"\fBDeprecated\fP
.RS 4
use \fBToUnknown()\fP Return the handle as a \fBTiXmlUnknown\fP. This may return null. 
.RE
.PP

.SS "\fBTiXmlUnknown\fP* TiXmlHandle::Unknown () const\fC [inline]\fP"\fBDeprecated\fP
.RS 4
use \fBToUnknown()\fP Return the handle as a \fBTiXmlUnknown\fP. This may return null. 
.RE
.PP

.SS "\fBTiXmlUnknown\fP* TiXmlHandle::Unknown () const\fC [inline]\fP"\fBDeprecated\fP
.RS 4
use \fBToUnknown()\fP Return the handle as a \fBTiXmlUnknown\fP. This may return null. 
.RE
.PP

.SS "\fBTiXmlUnknown\fP* TiXmlHandle::Unknown () const\fC [inline]\fP"\fBDeprecated\fP
.RS 4
use \fBToUnknown()\fP Return the handle as a \fBTiXmlUnknown\fP. This may return null. 
.RE
.PP


.SH "Author"
.PP 
Generated automatically by Doxygen for zebulon from the source code.
